06.2 builder

Workflow Builder

The Workflow Builder is the primary way to create workflows in BindAI.

It provides a fluent API for constructing workflow graphs by connecting nodes together in a readable and maintainable way.

Instead of manually managing workflow objects and connections, the builder handles the structure for you.

---

Why Use the Builder?

A workflow is fundamentally a graph.

Managing nodes and connections manually quickly becomes difficult as workflows grow.

The builder simplifies this process by allowing workflows to be constructed step by step.

---

Builder Pattern

The builder follows a fluent interface.

Conceptually:

Create Builder

↓

Add Nodes

↓

Connect Nodes

↓

Validate

↓

Build Workflow

Each operation returns the builder, allowing calls to be chained together.

---

Creating a Builder

A workflow begins with a builder instance.

from bindai_workflow import WorkflowBuilder

builder = WorkflowBuilder(
    name="Customer Support",
)

At this point the workflow exists only in memory.

---

Defining a Start Node

Every workflow begins with a start node.

builder.start_node()

This creates the workflow entry point.

---

Adding Nodes

Nodes are added sequentially.

Example:

builder.start_node()

builder.agent(
    support_agent,
)

builder.end_node()

Each node becomes connected to the previous node automatically.

---

Fluent Chaining

Because the builder is fluent, workflows can also be written as a chain.

workflow = (
    WorkflowBuilder()
    .start_node()
    .agent(agent)
    .end_node()
    .build()
)

This style is common for simple workflows.

---

Building the Workflow

When construction is complete:

workflow = builder.build()

The builder validates the workflow before returning it.

If validation fails, an exception is raised describing the problem.

---

Validation

The builder automatically checks common workflow errors.

Examples include:

• missing start node
• unreachable nodes
• duplicate node identifiers
• invalid connections
• missing end node

Validation helps detect problems before execution begins.

---

Registering Agents

When an agent node is added, the builder automatically registers the agent with the workflow.

Conceptually:

Agent

↓

Builder

↓

Workflow Registry

This allows agent nodes to reference the registered agent during execution.

---

Conditional Branches

Builders can create branching workflows.

Conceptually:

Agent

↓

Condition

↙       ↘

Yes     No

The condition determines which branch executes next.

---

Loops

Loops allow sections of a workflow to repeat.

Node

↓

Condition

↓

Repeat

↓

Continue

The loop exits when its predicate evaluates to false.

---

Parallel Execution

Builders also support parallel branches.

Parallel

↙      ↓      ↘

A      B      C

↓

Join

Each branch executes independently before synchronization.

---

Human Tasks

Human approval can be inserted into a workflow.

Agent

↓

Human Task

↓

Resume

↓

Continue

The workflow pauses until the human task is completed.

---

Variables

The builder does not manage workflow data directly.

Instead, nodes communicate through workflow variables stored in the execution context.

Node A

↓

Variables

↓

Node B

This keeps nodes independent and reusable.

---

Large Workflows

As workflows become larger, organizing related sections together improves readability.

Example structure:

Start

↓

Preparation

↓

Processing

↓

Validation

↓

Completion

Grouping related steps makes workflows easier to maintain.

---

Best Practices

• Start with a clear workflow objective.
• Keep nodes focused on a single responsibility.
• Use fluent chaining for small workflows.
• Use intermediate variables for complex workflows.
• Validate workflows before deployment.
• Prefer multiple small workflows over one extremely large workflow.
• Separate orchestration logic from business logic.

---

Summary

The Workflow Builder provides a simple, fluent interface for constructing workflow graphs.

It automatically manages node registration, connections, and validation, allowing developers to focus on workflow behavior rather than graph implementation details.